gEDA Project Wiki
(static html archive)

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== Symbol guide ======

===== General =====

A symbol is a small gEDA file (typically with the file extension “''.sym''”) that defines the graphical appearance, pins, and inherited attributes of a component.  It can be instantiated in a schematic as a component object.

==== Attributes ====

Attributes are text objects which follow the pattern “''name=value''”.  They can be attached to a net, pin, or component object, or they can not be attached to anything.  This allows five cases:

  * Attributes in a symbol which are attached to a pin define this pin's properties.  The four common pin attributes are ''pinnumber='', ''pinseq='', ''pinlabel='', and ''pintype=''.  There is no direct way to change these pin attributes from the instantiating schematic, but there's the [[geda:gnetlist_ug:slotting|slotting mechanism]] which allows changing pinnumbers depending on a ''slot='' attribute in the component.

  * Attributes in a symbol which aren't attached to anything make up the basic attributes of that symbol and are inherited by components instantiating the symbol.

  * Attributes attached to a component augment the attributes inherited from the symbol.  For most attributes, attaching an attribute with the same name as an inherited attribute will override the inherited value, and attaching an attribute with the value “''unknown''” will remove the inherited value.  Some attributes like ''net='' follow more complex rules.

  * Attributes can be attached to a net.  The only attribute for which this is typically done is “''netname=''”; it makes that net segment part of the net with the specified name, connecting separate net segments with the same ''netname='' attribute to form a single net.

  * Attributes in a schematic which aren't attached to anything are called “floating”.  They aren't too useful, but there are some backends which allow specifying global parameters via floating attributes.

Attributes must not contain a space before or after the “=” sign, and the value must not be empty.  If you want to specify an empty value, use “''unknown''” instead; this is a special value that is treated as “no value” by the netlister.


===== Symbol types =====

There are different types of symbols which are treated differently by gEDA/gaf:

==== Regular symbols ====

Regular symbols are the “bread and butter” symbol type.  They represent some basic unit—a component, some part of a component, or whatever is appropriate in the context—which can be connected to other such units via nets connected to their pins.

Regular components must have a ''refdes='' attribute.  If multiple components in a schematic have the same ''refdes='' attribute, they are treated as part of the same package; i.e., there will be a single package in the resulting netlist which contains all the pins and attributes of all the components which share that ''refdes=''.  It follows that a pinnumber must me unique, and there must not be attributes with conflicting values (except ''slot=''), within all components which share a common ''refdes=''.

It's recommended that regular symbols contain a ''refdes='' attribute with a placeholder value (e.g., “''U?''”, “''C?''”, or “''R?''”) which will be promoted on instantiation.  This way, the user just has to replace the “?” with a number and doesn't have to add a ''refdes='' attribute themselves.  It is common to add other attributes pre-populated with common or placeholder values, as well.

Recommended attributes:
  * ''refdes='' (with a placeholder value; e.g., “U?”, “C?”, or “R?”)
  * ''value=''
  * ''device='' (if used for simulation)
  * ''footprint='' (if used for layout)

Recommended pin attributes:
  * ''pinnumber='' (required, must be unique; contrary to its name, this doesn't have to be a number)
  * ''pinlabel='' (if you want to have an additional label for the pin)
  * ''pinseq='' (if used for simulation, or if the symbol is slotted)
  * ''pintype='' (if used with DRC)

== Slotting ==
If you have a package which contains multiple instances of the same functionality (e.g., a 7400 IC with four NAND gates), it would be inconvenient if you had to create a separate symbol with the correct pinnumbers for each slot.  Instead, you can create a single symbol and use the [[geda:gnetlist_ug:slotting|slotting mechanism]] to automatically change the pinnumbers depending on the value of the ''slot='' attribute.

== Symbols for mechanical parts ==
Symbols don't have to have pins.  If you want to treat some mechanical part (enclosure, screw, unplated or plated hole, copper antenna) as a component which will appear in the layout with its own footprint, you can do so.

Plated holes or other parts with electrical connectivity should have a pin that is connected to the appropriate net (e.g. ''GND'') in the schematic so the PCB editor knows about the connection and will warn if the part is connected to the wrong net.

==== Subschematic symbols ====

A symbol with a ''source='' attribute is considered a subschematic symbol.  As opposed to regular and graphical symbols, pins on subschematic symbols are named via ''pinlabel='' attributes.  They still have to have valid ''pinnumber='' attributes, though, which are used as a fallback if hierarchy traversal is disabled.

If hierarchy traversal is enabled, gnetlist creates an instance of the schematic file (or multiple schematic files separated with “,”) listed in the ''source='' attribute of each subschematic symbol, replacing the symbol with the contents of the subschematic and connecting the I/O ports in the subschematic with what is connected to the corresponding pins of the subschematic symbol.  If ''refdes='' mangling is enabled, the ''refdes='' of subschematic packages is prefixed/suffixed with the subschematic symbol's ''refdes='' depending on the mangling settings.

If hierarchy traversal is disabled, subschematic symbols are treated like regular symbols.

Recommended attributes:
  * ''refdes=''
  * ''source=''

Recommended pin attributes:
  * ''pinnumber='' (required, must be unique; only used if hierarchy traversal is disabled)
  * ''pinlabel='' (required, must be unique; only used if hierarchy traversal is enabled)

==== Power symbols ====

Power symbols indicate that what they are connected to is connected to some named net (usually a power rail; ''GND'', ''3.3V'', etc.).  Instead of a ''refdes='' attribute, they have a ''netname='' attribute indicating the name of the net.  Pins on power symbols mustn't have a ''pinnumber='' attribute; they shouldn't have any attribute at all.

Recommended attributes:
  * ''netname=''

Recommended pin attributes:
  * none

== Old-style power symbols ==
gEDA/gaf up to version 1.9.2 didn't support proper power symbols.  Instead, symbols which has exactly one pin connected to a named net via a ''net='' attribute were allowed not to have a ''netname='' attribute; this marked them as a power symbol.

For newer designs, power symbols with a ''netname='' attribute are recommended.

==== I/O port symbols ====

Subschematics are hooked up to the schematic from which they are instantiated via port symbols.  Instead of a ''refdes='' attribute, port symbols have a ''portname='' attribute; for each pin on the subschematic symbol, there should be exactly one I/O port in the subschematic whose ''portname='' attribute matches the ''pinlabel='' attribute of the pin.  Port symbols mustn't have a ''pinnumber='' attribute on their own pin.

Recommended attributes:
  * ''portname=''

Recommended pin attributes:
  * none

== Old-style I/O port symbols ==
gEDA/gaf up to version 1.9.2 didn't support proper port symbols.  Instead, symbols with exactly one pin whose ''refdes='' matched the ''pinlabel='' of the respective pin were used.

For newer designs, port symbols with a ''portname='' attribute are recommended.

==== Graphical symbols ====

Graphical components convey additional information about a schematic that doesn't change the semantics of the netlist itself.  They must have a ''graphical=1'' attribute (any other value is invalid) and can't have a ''refdes='' attribute.  gEDA/gaf doesn't assign a particular meaning to graphical components but passes them unchanged to netlist backends.  Users and backend authors are free to assign any meaning to them.  **Contrary to a common misconception, graphical components are NOT ignored by the netlister.**  They are collected in a separate list of graphical components which is passed to backends together with the netlist.

The most common application of graphical symbols is [[#how_do_i_create_a_titleblock_symbol|titleblocks]] and [[#how_do_i_create_an_nc_symbol|NC symbols]].

Recommended attributes:
  * ''graphical=1'' (required; any other value is invalid)

Recommended pin attributes:
  * ''pinnumber='' (required, must be unique)


===== FAQ =====

==== How do I create a titleblock symbol? ====

A titleblock symbol has to have a “''graphical=1''” attribute so it isn't included in the regular netlist.  Apart from that, you can draw it however you like.

If you plan to attach title, author, etc. as attributes, it makes sense to add pre-populated attributes to the symbol that will be promoted on instantiation.  You are free to choose whatever attribute names seem appropriate; the information entered here is available to but isn't currently used by netlist backends.

==== How do I create a symbol for a mechanical part? ====

Regular components are the only components listed in the BOM, so if you want to create a symbol for something that should be listed in the BOM, it has to be a regular symbol.

This means it is included in the netlist, so it has to have the proper attributes set, including a footprint.  Ideally, the footprint would match the physical geometry of the part and provide e.g. a silk outline, but you could also just use a dummy footprint.

If the part has electrical connectivity (e.g. a plated hole), it should have a pin that is connected to the appropriate net (e.g. ''GND'') in the schematic.  This makes sure the PCB editor knows about the connection and warns if the part is connected to the wrong net.

==== How do I create an NC symbol? ====

An NC symbol is used in a schematic to indicate that some pin shouldn't be connected to anything.  Using NC symbols is optional and doesn't have any effect on netlisting; however, if a pin which is connected to an NC symbol is also connected to something else, a DRC error is displayed.

NC symbols annotate the netlist with additional information but aren't “parts” by themselves, so they must be graphical symbols.  To create an NC symbol, use the following attributes:

  graphical=1
  device=DRC_Directive
  value=NoConnection

The symbol should have exactly one pin.  You can avoid having to create multiple NC symbols for multiple directions by making the pin zero units long.  (If you are using gEDA/gaf up to version 1.9.2, there is no way to do this in the GUI; you'll have to edit the symbol file manually.)

==== How do I create a default jumper symbol? ====

This depends on whether you want the default jumper to be listed in the BOM and visible in the layout or not.

If you want it to be listed in the BOM and/or visible in the layout, treat it as a regular component.  This means you'll have to assign it a ''refdes='' and a ''footprint='' and place its footprint on the correct pins of the pin header in the layout.

If you don't want it to be listed in the BOM nor visible in the layout, set ''graphical=1'' and don't use a ''refdes='' or ''footprint='' attribute.
gEDA Project Wiki(static html archive)

User Tools

Site Tools

Page Tools

gEDA Project Wiki
(static html archive)
